Address Book User Guide	Version 2.0

1














                                    ADDRESS BOOK







             Address and 'Phone Number Management for the Psion Series 3A





                                   Shareware Program



                               © 1994, 1995 John W Dawson



                                  V2.0, February 1995

1    Introduction

Address Book is an Application for the Psion Series 3A which you can use to 
manage addresses, 'phone numbers, and related information. It has a number of 
special features which make it more convenient and suitable for this purpose than 
the standard Database Application built into the Series 3A. These include:

*     Alphabetic listing and searching of names;

*     Enhanced DTMF dialling

*     Variable volume;

*     Automatic prefixing of charge card account number and PIN

*     Automatic prefixing of network service codes (for call diversion etc.);

*     Linking of records, to allow common information to be defined once only but
      shared by more than entry.

The Application manages one or more database of information about an individual 
or an organisation. Each entry in a database has the same layout, but the 
template for this is fully configurable.

Two of the fields have special significance, since they are used to sort the 
entries. In the default template they have the labels Name and Organisation; 
however you can change their labels and positions in the template.

An entry may relate to a person, in which case the Name field will be present and 
optionally an Organisation. Alternatively the entry may relate to a Company or 
other organisation, in which case there will no Name, only an Organisation.

There are four principle screens

The Find  screen lists entries in alphabetical order, and allows alphabetic 
searches.

The Show screen displays a single entry in full.

The Update screen allows existing entries to be modified.

The Add screen allows new entries to be added.

2    Getting Started

2.1    Installation

To install the Application carry out the following steps

1    Copy the file ADDBKV2.OPA into the \APP directory on the Internal Drive or
     an SSD.

2    Copy the files ADDBK2V2.OPO, IXFILEV1.OPO, and DIALOGV2.OPO into the \OPO 
      directory on the same drive.

3    On the System screen use the "Install" (Psion-I) command to install ADDBKV2.
     The Address Book icon (depicting a book, 'phone, and envelope) should now 
     appear on the screen. 

4    You may find it convenient to assign a button to the Application, using the 
     "Assign Button" (Psion-A) command.

2.2    Creating a new Address Book

You can now create an Address Book database by using the "New File" (Psion-N) 
command (while the highlight is beneath the Address Book icon). In the dialog box 
specify the name for the database and the drive where it is to be located.

The Edit Labels screen will now be displayed, allowing you to customise the 
default template to your preferences. If the default is acceptable just type 
Escape. Otherwise edit the labels; keys work in the same way as on the Add and 
Modify screens described below. Type Enter when finished.

A dialog will then be displayed, to allow you to specify which fields to use for 
sorting, and the format you wish to enter names in. The choice of format is 
either forename(s) followed by surname (e.g. "Sally Ann Field") or surname 
followed by forename(s) (e.g. "Field,Sally Ann"). You can choose the character 
used to separate the forenames and surnames; this can be a space, a comma, or 
some other custom character. Alternatively you can specify "None", in which case 
names are not split into separate forename and surname parts. This last option 
would be most suitable if you wished to use Address Book to manage information 
other than names and addresses.

On completion of the dialog the Add screen (described fully below) will then be 
displayed, enabling you to start adding entries to the database.

Once you have some entries in the database you can go to the Find screen by 
typing Escape or Diamond.

2.3    Using an existing Database

If you have an address database in standard Psion DBF format (e.g. created using 
the built in Data application or an OPL program) then you can open this with 
Address Book. You can not use a Database that contains numeric fields, but any 
Database which the built-in Database can open should be okay.

Databases which have been created and maintained by Address Book have an extra 
'index' file associated with them. When Address Book first opens a database where 
this index information is not available then, it must build this index. Once 
created there should be no need to rebuild this index, unless the index is 
accidentally deleted or the database file is modified by an application other 
than Address Book.

Open the file in the normal way (from the System screen). If the database does 
not contain a template (typically a file created by an OPL application) then the 
Edit Labels screen is displayed. The default template is shown, and you should 
modify this to reflect the structure of entries in the database. (If there is a 
template already present in the database then Address Book will use this.)

A dialog is then shown to allow you to specify how the database is to be sorted 
and the layout of the Name field (as when creating a new file). There are extra 
dialog lines which allow you to control whether entries which contain more than 
one name in the Name field are split into multiple linked entries.

If you set Name Separator to "None" then no changes will be made to entries in 
your database. Otherwise if an entry contains more than one name (separated by 
the specified character) then extra database entries are created for the second 
and subsequent names, which are all linked to the entry for the first name. (See 
below for explanation of linking).

The application will now build the index. When this is complete the Find screen 
is displayed, listing the entries in alphabetic order.

3    General Points

Most of the basic features operate in the 'standard' way. Diamond/Shift-Diamond 
switches to the next/previous screen. Menu displays the menus. Control-Menu 
controls the displaying of the Status Window.

The Find, Show, Update, and Add screens can all be zoomed, by typing Psion-Z or 
Shift-Psion-Z. The "About Address Book" (Shift-Psion-A) command displays the 
introductory screen. You can exit cleanly from the Application by using the 
"Exit" (Psion-X) command in any screen.

4    The Find Screen

Entries are listed in alphabetical order. Entries for People are sorted by 
surname, which is generally taken to be the final space-separated 'word' in a 
name. E.g. John William Hedges and Peter Hetherington-Whyte would both be listed 
under H. 

You can override this, to cater for exceptions such as double-barrelled surnames 
without hyphens, e.g. Ralph Vaughan Williams which should be listed under V. You 
should enter such names with a double space between the last forename and the 
start of the surname (e.g. between Ralph and Vaughan).

The È character indicates the 'current' entry.

Entries for Organisations are sorted by their complete names; e.g. Acme Software 
Company would be listed under A.

You can find an entry by typing the initial letters of its surname (or complete 
name for an organisation). Use lower case letters only. As you type the program 
will progressively find the first entry which matches the letters entered, and 
display the entry with the matched letters highlighted.

Upper and lower case characters are treated as equivalent. Accented characters 
are sorted and matched as the equivalent unaccented character; "¾" is treated as 
"a", "¿" as "o", and "§" as "s". Punctuation characters are ignored when sorting 
and matching; e.g. O'Regan is listed between Oppenheimer and Oswald, and can be 
found by typing o r ....

If you make a mistake when typing the sequence of initial letters then press the 
Escape key; this cancels the matching, and enables you to start the sequence 
again from the first letter.

Once the entry you require is displayed on the screen you can select it 
immediately by typing the digit or shifted letter shown to the left of it. The 
entry is then shown in full on the Show screen. Enter or Diamond displays the 
current entry in full.

You can move up and down the screen using the Up/Down arrow keys. Page Up/Down 
move a whole screenfull at a time. Home moves to the first entry, End to the 
last. Use of any of these keys cancels any matching in progress.

5    The Show Screen

This displays the full details for a single entry. Only fields which have 
information in them are shown.

If the entry is too big to be shown in full then you can scroll up and down, 
using Up/Down/Page-Up/Page-Down. Alternatively you can zoom to a smaller font.

Typing any lower case letter starts a 'quick-find' the Find screen is displayed 
with the first entry starting with the letter selected.

6    The Update Screen

You can update the current entry by using the "Update" (Psion-U) command on the 
Find or Show screens, or by pressing Diamond on the Show screen. The Update 
screen is then displayed, showing all the fields for the entry and their current 
values if any.

You can now change these values by typing text on the keyboard. If all or part of 
a field is highlighted then this is replaced by what you type; otherwise text is 
added at the cursor position. You can put line breaks in any of the fields by 
typing Shift-Enter.

Use the arrow keys to move around within a field or between fields. Use these 
keys with Shift down to highlight text. Control-Left/Right moves a word at a 
time. Home and End take you to the start and end of the current line.

The Delete key removes the highlighted text, or the character to the left of the 
cursor if nothing is highlighted. You can cut and paste text between fields using 
Delete or "Copy" (Psion-C) with text highlighted and then "Insert" (Psion-I).

If the contents of a field are too long to fit on the screen then they are 
scrolled automatically as you enter text or move around.

The Enter key writes the modified entry back into the database. An entry will not 
be updated if both the Name and Organisation fields are blank. Use Escape to 
abandon the update, leaving the entry unchanged in the database.

7    The Add Screen

You can add new entries to your database by using the "Add" (Psion-A) command or 
by pressing the Diamond key on the Update screen or Shift-Diamond on the Find 
screen. This takes you to the Add screen, whose operation is similar to the 
Update screen described above, except that all fields are initially blank.

8    Finding Entries

The principle way of finding a particular entry is by alphabetical searching by 
name on the Find screen. However you can also make searches on other fields, 
using the "Find" (Psion-F) command. In the dialog you then specify the text you 
are looking for, which field to search (or all fields), whether the search should 
be case sensitive, and whether the entire field must match the specified text.

The first entry which matches the criteria (if any) is then displayed on the Show 
screen. You can find further entries matching the same criteria using "Find Next" 
(Psion-G).

Note that "Find" and "Find Next" find search the database in physical order, 
which may not be the same as the sorted order in which entries appear on the Find 
screen.

9    Deleting Entries

An entry can be deleted using the "Delete" (Psion-D) command, or by typing the 
Delete key on the Find or Show screens. You are asked to confirm the deletion 
before the entry is removed from the database.

10    Linking Entries

This facility allows more than one entry to share the same common information. 
The sort of situation where this might be useful is where you have a couple who 
have the same address and home 'phone numbers, but different work 'phone numbers. 
Each individual can have their own separate entry, but the common address and 
home 'phone is only defined in one entry; the other entry refers to this 'parent' 
entry. If the couple should move then you only need to change the address in one 
place.

Another way of using linking is to set up a 'parent' entry for a Company, and 
have several linked entries for individuals in the Company.

You can create a new entry linked to an existing 'parent' entry using the "Add 
Linked Entry" (Psion-L) command. The 'parent' entry must be the current entry on 
the Find or Show screen. The Add screen will then be displayed, with the field 
contents derived from the 'parent' shown in grey. These values cannot be 
modified, but can be replaced by typing new contents.

You can link an existing entry to an existing 'parent' using the "Link" (Shift-
Psion-L) command. First select the entry to be linked on the Find or Show screen 
and type Shift-Psion-L. Then select the required parent and type Shift-Psion-L 
again.

An entry can only be linked to a single 'parent', but a 'parent' entry can have 
any number of other entries linked to it.

When a linked entry is displayed on the Show  screen then for any of its fields 
which are blank the contents of the field in the 'parent' entry are shown 
instead. You can suppress the showing of field contents derived from the 'parent' 
by entering a single space in the field.

When you update a linked entry, fields derived from the 'parent' are shown in 
grey and cannot be changed, only replaced.

You can remove a link from an entry with the "Remove Link" (Shift-Psion-U) 
command. You are asked to confirm the removal.

11    Counting Entries

The "Show Number" (Psion-N) command on the Entries menu displays briefly the 
total number of records in the database in the bottom right corner of the screen.

12    DTMF Dialling

You can dial the current entry on the Find or Show screen by typing Dial (Psion-
Help). This displays the Dialling screen which lists all the telephone numbers 
for that entry. Select the number you wish to dial using the Up and Down keys.

The Tab key dials the number exactly as shown. Enter prefixes the "dial out" 
code, e.g. to make an outside call via a switchboard. Type c to automatically 
prefix the account number and PIN for a BT charge card call (or similar). Type d 
to dial the number with the code and terminator for a special service (such as BT 
Star Services Call Diversion). Type Escape to quit from the Dial screen.

After any of these buttons are pressed there is a short delay; this allows you to 
position the loudspeaker correctly for successful dialling. You can dial further 
digits by pressing any of the 0 to 9 and *, # keys while the Dial screen is 
displayed.

If a 'phone number entry contains non-diallable characters, then only the digits 
preceding the first such character will be dialled. E.g. if an entry contains 
"0123 456789 x321" then only 0123 456789 will actually be dialled. Spaces or 
hyphens may be used to separate parts of 'phone numbers.

This version of the program does not support international dialling. However 
numbers should be dialled correctly when making calls within the same country, 
even where the numbers have been entered in standard Psion international format, 
so long as any national prefix is included  (e.g. 1 321 4567890 [USA]).

Note the c and  d buttons will not be displayed or activated until you have set 
up an account number and PIN or service code; use the "Dialling Setup" (Shift-
Psion-D) command to display the Dialling Setup Dialog. When setting up the Divert 
Code specify both the code prefix and the terminator, separated by a space. E.g. 
for Star Services "Divert on No Reply" you should set *61* #.

You can also set the code required to obtain an outside line. E.g. if you have to 
dial 9 and then wait for a second dial tone you should set 9,.

 The other fields allow you to specify the duration of the tones, the pause 
between tones, and the length of a delay; units are 1/32s of a second. You can 
also set the volume of the tones; allowed values are 0 to 5, with 5 the quietest. 
(5 seems to give the most reliable results with most 'phones.)

13    Printing

This program does not support direct output to a printer attached to the Psion. 
However you can output to a text file, which can then be printed using the built-
in Word application, or transferred to an external PC for printing.

The "Print" (Psion-P) command brings up the Print dialog. This allows you to 
specify

*     whether All entries in the database are printed, or selected Individual
       entries;

*     whether fields with blank contents are printed; 

*     whether the field labels are printed;

*     the drive and specification for the Destination file.

If you specified All entries, then these are printed immediately you terminate 
the dialog with Return. 

If you specified Individual entries then you must select each entry that you wish 
to print (on the Find screen) and use the "Print Entry" (Psion-P) command. When 
all required entries have been printed you terminate printing with the "Finish 
Printing" (Shift-Psion-P) command. 

14    Editing Labels

You can modify the labels template by using the "Edit Labels" (Psion-E) command. 
The Edit Labels screen is then displayed. Keys operate as on the Add and Update 
screens. Use Shift-Dial (Psion-Shift-Help) to insert the 'phone symbol at the 
start of a label, to indicate that the field is diallable.

It is not advisable to add or remove labels in the middle of the template, as 
data in existing records will become misaligned with the labels. It is okay 
however to add new fields to the end of the template.

15    Converting from Address Book V1.0

If you have a database that was created using Address Book V1.0, then you must 
first convert the file before you can open it with Address Book V2.0, since the 
file formats are different.

Copy the file CONVADBK.OPA to \APP on the same drive as you installed the main 
application, and install it on the System screen. Select the database beneath the 
conversion program icon, and press Enter.

In the dialog box specify a new name for the database (no directory path or 
extension). The Edit Labels screen is then displayed, allowing you to customise 
the default template to your preferences. However if you delete or modify any of 
the label names then data in fields corresponding to these labels will not be 
transferred into the new file. You can delete labels corresponding to fields you 
were not using in the original database, and add labels for new fields which will 
be initially blank. You can change the labels of any of the fields after 
conversion, using "Edit Labels" in the main application.

After pressing Enter (or Escape to use the default template), the program will 
convert your database, displaying progress in the bottom right corner of the 
screen.

Once all your databases have been converted you can remove CONVADBK.OPA from your 
disk.

16    Problems and Troubleshooting

The only known bug at time of writing is that very occasionally the application 
aborts with the alert message "Read failure", "Unknown error[0]". The database 
and the index file are left intact, and the operation that caused the failure can 
be repeated successfully.

The most likely problems to be encountered are associated with running out of 
memory. This is most likely when attempting to display a new screen or dialog. 
The program is designed to trap such occurrences and either abandon what it was 
trying to do or exit gracefully.

If the program should exit in an uncontrolled way, or has to killed off (because 
it appears to be locked up), then when it restarts it may display the message 
"Index file is obsolete". This is the result of a check it performs to see 
whether the database has been modified by another application, which would make 
it inconsistent with the index. If the database has not in fact been modified 
then it should be okay to continue.

If the program should start behaving erratically (e.g. listing entries in wrong 
order or missing out some entries) this may indicate corruption or inconsistency 
in the index file. In such cases it is best to exit, and delete the index file. 
Then when the database is reopened Address Book will rebuild the index.

I will be pleased to receive any queries or comments about this program. I can be 
contacted via

CIX           jdawson

Compuserve    100415,370

Email         jdawson@cix.compulink.co.uk

'Phone        +44 1734 666185

Snailmail    19, St Edward's Rd.
             Reading
             Berkshire
             RG6 1NL
             England

Please 'phone outside working hours if possible, and not after 11pm UK time!

17    File Formats and Compatibility

By default Address Book files are created in \ADD directories, and have extension 
".ADD", as in V1.0. Unlike V1.0, V2.0 uses a standard DBF format which should be 
compatible with the built-in Database and other applications. Hence these other 
applications should be able to read files created by Address Book.

However it is not recommended that other applications are used to modify or add 
to files being maintained by Address Book. The reason for  this is that Address 
Book maintains information in a separate 'index' file, which it uses to list 
entries alphabetically. This 'index' file must be updated in step with changes to 
the main database file.

It appears that the built-in Database application automatically compresses a DBF 
file on exit, even if no changes were actually made to the file. Since this has 
the undesirable effect of making the file inconsistent with its index, Address 
Book sets the database file attributes to read-only on exit, in order to prevent. 
However some other applications, e.g. JBData, will not open a read-only file. 
Thus before opening the file with such an application you must set the file 
attributes to "read-only" = "No", using Psion-T on the System screen.

If the database file is made inconsistent with the 'index' file, then it is 
possible to reconstruct the index, though this does take significant time. Also 
any links which have been set up will be lost, since information about these is 
also held in the index file. No actual data is lost, and the links can be 
restored manually, i.e. using the Psion-Shift-L command.

The 'index' file has the same name as the main DBF file, but with extension 
".IDX". It is normally created on the same drive as the DBF file, except where 
this is a flash SSD. In this case the index file is created on the internal 
drive.

18    Registration

I am making this program available as Shareware. There is no registration 
procedure; the software as distributed is fully operational. However if you find 
this program useful then I would ask you to send a  donation (suggested £10 
Sterling) to a charity I am closely involved with. Reading Steiner School Project 
(Registered Charity No. 297857) is developing education in the Reading area based 
on the work of the Austrian educationalist and philosopher Rudolf Steiner.

Please make cheques etc. payable to R.S.S.P., and send them to

    Department ADBK
    Alder Bridge School
    Mill Lane
    Padworth
    Reading
    England
    RG7 4JU

Please do not send any technical queries etc. to the School!

Please do distribute this program freely, providing you do not make any charge 
(other than to cover reasonable costs of distribution) and you include these 
notes.

19    Future Developments

I have developed this program for my own use, so its facilities and operation 
very much reflect my own requirements. However there are a number of obvious ways 
it could be extended and developed, to make it more useful to a wider range of 
people. And many thanks for the useful suggestions I have received from those who 
tried out version 1.0. 

Future plans include

*     Full support for international dialling.

*     Allowing an additional field (e.g. a 'phone number) to be displayed on the 
      Find screen. This would be user configurable, as well as the position of 
      all the fields on the screen.

*     Exporting and importing to/from text files and other DBF files. The mapping 
      between fields in the  files would be configurable, allowing exchange of 
      data with databases that have a different record layout.

*     Configurable print layouts. This would allow you to select which fields are 
      printed, and in which order. An option for generating output in RTF format 
      (for printing via a compatible  word processor on a PC) will be provided 
      again (this was in version 1.0, but not re-implemented for 2.0). These 
      facilities will enable addresses to be printed on envelopes or labels.

*     "Find" will have an option to list the subset of records matching the 
      search criteria (as in 1.0 but not re-implemented in 2.0).

*     Implementation of Link-Paste (the "Bring" command), to facilitate exchange 
      of data with other Psion applications.

*     The facility to define "tags" or labels which could be applied to 
      individual records. Lists of entries which have a specific tag could then 
      be displayed.

20    Thanks

To those who have made invaluable technical information available via CIX and 
CIS.

To all those who paid registrations for V1.0, and provided encouragement and 
ideas for V2.0. Note that some of these ideas have not been implemented in this 
release, but are not being ignored, and will hopefully be implemented in later 
releases.